home *** CD-ROM | disk | FTP | other *** search
/ Directorty Opus 5 - Magellan 2 / Opus 5 - Magellan 2.iso / Extras / opussdk / docs / iff.doc < prev    next >
Text File  |  1996-09-05  |  11KB  |  391 lines
  1. TABLE OF CONTENTS
  2.  
  3. dopus5.library/IFFChunkID
  4. dopus5.library/IFFChunkRemain
  5. dopus5.library/IFFChunkSize
  6. dopus5.library/IFFClose
  7. dopus5.library/IFFFailure
  8. dopus5.library/IFFGetForm
  9. dopus5.library/IFFNextChunk
  10. dopus5.library/IFFOpen
  11. dopus5.library/IFFPopChunk
  12. dopus5.library/IFFPushChunk
  13. dopus5.library/IFFReadChunkBytes
  14. dopus5.library/IFFWriteChunkBytes
  15. dopus5.library/IFFWriteChunk
  16. dopus5.library/IFFChunkID                           dopus5.library/IFFChunkID
  17.  
  18.     NAME
  19.         IFFChunkID - get current chunk ID
  20.  
  21.     SYNOPSIS
  22.         IFFChunkID(handle)
  23.                      A0
  24.  
  25.         ULONG IFFChunkID(APTR);
  26.  
  27.     FUNCTION
  28.         Returns the four-byte ID of the current chunk.
  29.  
  30.     INPUTS
  31.         handle - IFF handle
  32.  
  33.     RESULT
  34.         Returns chunk ID.
  35.  
  36.     SEE ALSO
  37.         IFFOpen(), IFFGetFORM(), IFFNextChunk()
  38.  
  39. dopus5.library/IFFChunkRemain                   dopus5.library/IFFChunkRemain
  40.  
  41.     NAME
  42.         IFFChunkRemain - return size of remaining data
  43.  
  44.     SYNOPSIS
  45.         IFFChunkRemain(handle)
  46.                          A0
  47.  
  48.         long IFFChunkRemain(APTR);
  49.  
  50.     FUNCTION
  51.         Returns the amout of data left to be read in the current chunk.
  52.  
  53.     INPUTS
  54.         handle - IFF handle
  55.  
  56.     RESULT
  57.         Returns size of data or 0 if no data left.
  58.  
  59.     SEE ALSO
  60.         IFFOpen(), IFFNextChunk(), IFFChunkSize(), IFFReadChunkBytes()
  61.  
  62. dopus5.library/IFFChunkSize                       dopus5.library/IFFChunkSize
  63.  
  64.     NAME
  65.         IFFChunkSize - size of current chunk
  66.  
  67.     SYNOPSIS
  68.         IFFChunkSize(handle)
  69.                        A0
  70.  
  71.         long IFFChunkSize(APTR);
  72.  
  73.     FUNCTION
  74.         Obtain the amount of data in the current chunk.
  75.  
  76.     INPUTS
  77.         handle - IFF handle
  78.  
  79.     RESULT
  80.         Returns the total number of bytes of data in the current chunk
  81.         (excluding the chunk header). If there is no valid current chunk,
  82.         returns -1.
  83.  
  84.     SEE ALSO
  85.         IFFOpen(), IFFNextChunk(), IFFChunkRemain(), IFFReadChunkBytes()
  86.  
  87. dopus5.library/IFFClose                               dopus5.library/IFFClose
  88.  
  89.     NAME
  90.         IFFClose - close an IFF file
  91.  
  92.     SYNOPSIS
  93.         IFFClose(handle)
  94.                    A0
  95.  
  96.         void IFFClose(APTR);
  97.  
  98.     FUNCTION
  99.         Closes an IFF file.
  100.  
  101.     INPUTS
  102.         handle - file to close
  103.  
  104.     RESULT
  105.         The file is closed.
  106.  
  107.     SEE ALSO
  108.         IFFOpen()
  109.  
  110. dopus5.library/IFFFailure                           dopus5.library/IFFFailure
  111.  
  112.     NAME
  113.         IFFFailure - indicate failure to "safe" file routine
  114.  
  115.     SYNOPSIS
  116.         IFFFailure(handle)
  117.                      A0
  118.  
  119.         void IFFFailure(APTR)
  120.  
  121.     FUNCTION
  122.         The IFFOpen() routine has a "safe" mode, where an existing IFF file
  123.         is renamed rather than being over-written. If you create a file in
  124.         this safe mode, and then subsequent IFF operations fail (with the
  125.         result that the whole operation fails), you should call this routine.
  126.         Then, when you call IFFClose(), the pre-existing file will be
  127.         renamed back to what it was instead of being deleted.
  128.  
  129.     INPUTS
  130.         handle - IFF handle
  131.  
  132.     RESULT
  133.         The 'failure' flag is set, and the "safe" file will be restored.
  134.  
  135.     SEE ALSO
  136.         IFFOpen(), IFFClose()
  137.  
  138. dopus5.library/IFFGetForm                           dopus5.library/IFFGetForm
  139.  
  140.     NAME
  141.         IFFGetForm - get current FORM ID
  142.  
  143.     SYNOPSIS
  144.         IFFGetForm(handle)
  145.                      A0
  146.  
  147.         ULONG IFFGetForm(APTR);
  148.  
  149.     FUNCTION
  150.         This routine returns the four-byte FORM ID of the file.
  151.  
  152.     INPUTS
  153.         handle - IFF handle
  154.  
  155.     RESULT
  156.         Returns the FORM ID, or 0 if no valid FORM.
  157.  
  158.     SEE ALSO
  159.         IFFOpen(), IFFChunkID()
  160.  
  161. dopus5.library/IFFNextChunk                       dopus5.library/IFFNextChunk
  162.  
  163.     NAME
  164.         IFFNextChunk - skip to the next chunk
  165.  
  166.     SYNOPSIS
  167.         IFFNextChunk(handle, chunkid)
  168.                        A0       D0
  169.  
  170.         ULONG IFFNextChunk(APTR, ULONG);
  171.  
  172.     FUNCTION
  173.         This is the main work-horse of the IFF routines. This function will
  174.         scan through the IFF file from the current position looking for the
  175.         next chunk. You can optionally specify a chunk to look for.
  176.  
  177.     INPUTS
  178.         handle - IFF handle
  179.         chunkid - ID of chunk to look for, or 0 for next chunk
  180.  
  181.     RESULT
  182.         Returns ID of the new chunk, or 0 for error or end-of-file.
  183.  
  184.     NOTES
  185.         The IFF routines do not handle LISTs, CATs or other complicated IFF
  186.         structures. This routine will handle multiple FORMs within the one
  187.         file, which allows it to read ANIMs.
  188.  
  189.     SEE ALSO
  190.         IFFOpen(), IFFReadChunkBytes()
  191.  
  192. dopus5.library/IFFOpen                                 dopus5.library/IFFOpen
  193.  
  194.     NAME
  195.         IFFOpen - open an IFF file
  196.  
  197.     SYNOPSIS
  198.         IFFOpen(name, mode, form)
  199.                  A0    D0    D1
  200.  
  201.         APTR IFFOpen(char *, USHORT, ULONG);
  202.  
  203.     FUNCTION
  204.         This routine opens either a disk-based file or the clipboard for
  205.         IFF reading/writing. This and the other IFF routines in the
  206.         dopus5.library are far simpler (and seem to be less buggy) than the
  207.         iffparse.library functions. These routines were specifically designed
  208.         to make the reading and writing of "normal" IFF files as easy as
  209.         possible. They use the buffered IO routines for high performance.
  210.         They do not support LISTs, CATs or other complicated IFF structures.
  211.  
  212.     INPUTS
  213.         name - Filename or clipboard unit to open.
  214.         mode - Mode to open in :
  215.  
  216.                    IFF_READ       - open for reading
  217.                    IFF_WRITE      - open for writing
  218.                    IFF_CLIP_READ  - open clipboard for reading
  219.                    IFF_CLIP_WRITE - open clipboard for writing
  220.  
  221.                This flag can be set in conjunction with IFF_WRITE :
  222.  
  223.                    IFF_SAFE       - backup existing file
  224.  
  225.         form - If this is not 0, it specifies an IFF FORM. If you open
  226.                the file for reading, it will be tested against this FORM and
  227.                the open will fail if the FORM does not match. If you open
  228.                for writing, this specifies the FORM of the file to be
  229.                created.
  230.  
  231.     RESULT
  232.         If successful, returns an IFF handle which you use in all subsequent
  233.         calls to the IFF routines. Returns 0 on failure, and IoErr() is set
  234.         to the reason for the failure.
  235.  
  236.     NOTES
  237.         To use the clipboard, you must specify either IFF_CLIP_READ or
  238.         IFF_CLIP_WRITE. The clipboard unit you want is passed as the name
  239.         parameter. For example, to open clipboard unit 3 to write an ILBM,
  240.  
  241.             handle = IFFOpen( (char *)3, IFF_CLIP_WRITE, ID_ILBM );
  242.  
  243.         If you specify IFF_WRITE|IFF_SAFE, and the file you are creating
  244.         already exists, it will be renamed to a temporary filename. When
  245.         IFFClose() is called, the temporary file will be deleted. If you
  246.         call IFFFailure() because of a failure at some stage, it sets a flag
  247.         which causes the old file to be restored.
  248.  
  249.     SEE ALSO
  250.         IFFClose(), IFFFailure()
  251.  
  252. dopus5.library/IFFPopChunk                         dopus5.library/IFFPopChunk
  253.  
  254.     NAME
  255.         IFFPopChunk - flush the chunk cache
  256.  
  257.     SYNOPSIS
  258.         IFFPopChunk(handle)
  259.                       A0
  260.  
  261.         long IFFPopChunk(APTR);
  262.  
  263.     FUNCTION
  264.         This function flushes the current chunk write cache and writes the
  265.         chunk to disk.
  266.  
  267.     INPUTS
  268.         handle - IFF handle
  269.  
  270.     RESULT
  271.         The current chunk is written to disk. Returns TRUE if successful.
  272.  
  273.     SEE ALSO
  274.         IFFOpen(), IFFPushChunk(), IFFWriteChunkBytes()
  275.  
  276. dopus5.library/IFFPushChunk                       dopus5.library/IFFPushChunk
  277.  
  278.     NAME
  279.         IFFPushChunk - start writing a chunk
  280.  
  281.     SYNOPSIS
  282.         IFFPushChunk(handle, id)
  283.                        A0    D0
  284.  
  285.         long IFFPushChunk(APTR, ULONG);
  286.  
  287.     FUNCTION
  288.         This routine initialises a new chunk to be written to the file.
  289.         It is similar in concept to the PushChunk() routine in
  290.         iffparse.library, but does not support nesting of chunks. Therefore,
  291.         you should always call IFFPopChunk() before you call IFFPushChunk()
  292.         again.
  293.  
  294.     INPUTS
  295.         handle - IFF handle
  296.         id - ID of chunk to write
  297.  
  298.     RESULT
  299.         The chunk is initialised for writing. The usual procedure is :
  300.  
  301.             1. IFFPushChunk()
  302.             2. One or more calls to IFFWriteChunkBytes()
  303.             3. IFFPopChunk()
  304.  
  305.     SEE ALSO
  306.         IFFOpen(), IFFWriteChunkBytes(), IFFPopChunk()
  307.  
  308. dopus5.library/IFFReadChunkBytes             dopus5.library/IFFReadChunkBytes
  309.  
  310.     NAME
  311.         IFFReadChunkBytes - read data from a chunk
  312.  
  313.     SYNOPSIS
  314.         IFFReadChunkBytes(handle, buffer, size)
  315.                             A0      A1     D0
  316.  
  317.         long IFFReadChunkBytes(APTR, APTR, long);
  318.  
  319.     FUNCTION
  320.         This routine reads data from the current position in the current
  321.         chunk.
  322.  
  323.     INPUTS
  324.         handle - IFF handle
  325.         buffer - buffer to store data
  326.         size - amount of data to read
  327.  
  328.     RESULT
  329.         Returns the amount of data read or -1 for failure. Will not read
  330.         past the end of a chunk.
  331.  
  332.     SEE ALSO
  333.         IFFOpen(), IFFNextChunk(), IFFChunkSize()
  334.  
  335. dopus5.library/IFFWriteChunkBytes           dopus5.library/IFFWriteChunkBytes
  336.  
  337.     NAME
  338.         IFFWriteChunkBytes - write data in a chunk
  339.  
  340.     SYNOPSIS
  341.         IFFWriteChunkBytes(handle, data, size)
  342.                              A0     A1    D0
  343.  
  344.         long IFFWriteChunkBytes(APTR, APTR, long);
  345.  
  346.     FUNCTION
  347.         This routine writes data to a chunk that was initialised with
  348.         PushChunk(). The data is generally cached and not written to the disk
  349.         until PopChunk() is called, resulting in higher performance.
  350.  
  351.     INPUTS
  352.         handle - IFF handle
  353.         data - data to write
  354.         size - amount of data
  355.  
  356.     RESULT
  357.         Returns TRUE if successful.
  358.  
  359.     SEE ALSO
  360.         IFFOpen(), IFFPushChunk(), IFFPopChunk()
  361.  
  362. dopus5.library/IFFWriteChunk                     dopus5.library/IFFWriteChunk
  363.  
  364.     NAME
  365.         IFFWriteChunk - write a chunk straight out
  366.  
  367.     SYNOPSIS
  368.         IFFWriteChunk(handle, data, id, size)
  369.                         A0     A1   D0   D1
  370.  
  371.         long IFFWriteChunk(APTR, APTR, ULONG, ULONG);
  372.  
  373.     FUNCTION
  374.         If you have a single structure or piece of data you wish to write
  375.         as a chunk, this routine is simpler than the PushChunk()/PopChunk()
  376.         method.
  377.  
  378.     INPUTS
  379.         handle - IFF handle
  380.         data - data to write
  381.         id - ID of chunk
  382.         size - size of data
  383.  
  384.     RESULT
  385.         If successful, the chunk is written straight to the file. Returns
  386.         FALSE on failure.
  387.  
  388.     SEE ALSO
  389.         IFFOpen(), IFFPushChunk(), IFFPopChunk(), IFFWriteChunkBytes()
  390.  
  391.